Back to Contents Previous Next
6. Panes **
A ‘pane’ is a window which, when displayed, appears to be attached to another window - its parent window - and (usually) moves around with it if the parent window is moved. Toolbars are common examples of panes - the toolbar being a separately-defined window but ‘attached’ to a parent window.
Single pane
DrWimp has easy arrangements to attach a pane to a window. From the Tutorials folder (Tutor1 sub-directory) copy “Template3” into the !MyApp directory and rename as “Templates”.
Where the other windows are loaded in, load in the window “pane” with:
pane%=FNwimp_loadwindow(“<MyApp$Dir>.Templates”,“pane”,0)
We are going to attach this pane to the window main%
.
When a window is dragged about etc., it is actually being continually closed/re-opened all the time. This means that PROCuser_openwindow
is also being called continually just before the window in question is opened. So, to effect a pane, every time the main window is opened we want to first open the pane in the window stack position that is supplied (which would be the stack position that the main window would take if there was no pane). Then we want to open the main window just behind this.
We achieve this by using FNuser_pane
, which tells DrWimp which pane belongs to which window and causes the parent window to be opened behind its declared pane. To show this, first add the following lines in PROCuser_openwindow
:
IF window%=main% THEN
xoff%=x%-FNwimp_getwindowvisiblesize(pane%,0)
PROCwimp_openwindowat(pane%,xoff%,y%,stack%)
ENDIF
This automatically causes the pane to be opened first with main%
opened behind it. (The ‘getwindowvisiblesize’ call is not part of the essential sequence: it is merely placing the pane accurately.)
The pane also needs to be closed when the main window is, so in PROCuser_closewindow
add the following line:
IF window%=main% THEN PROCwimp_closewindow(pane%)
Then, most importantly, change FNuser_pane
as follows, to tell DrWimp that the window has a pane:
DEF FNuser_pane(window%)
return%=-1
IF window%=main% THEN return%=pane%
=return%
Re-load !MyApp and check that it is working.
Just a quick explanation of a few other related things:
PROCwimp_openwindowat(window%,x%,y%,stack%)
opens a specified window so that the top left corner is at the co-ordinates
x%
,
y%
. If you want the window to open on top, then
stack% = -1
, or at the bottom if
stack%=2
. If you want the window to open behind a certain one, then
stack% =
‘the handle of the window to open behind’ - and this latter is used in multiple panes, see below. Finally, stack%
values of -3 and -4 have the same meaning as in PROCwimp_openwindow()
.
If you want a window to open with another one but not follow it around the screen, then in
PROCuser_openwindow
, use
PROCwimp_openwindow
. If you set the second parameter to 1 then it will continually re-centre, so it is best to set it to 0. Also, just pass
stack%
straight through.
Multiple panes
Multiple panes are straightforward, but you now have to decide the ‘stacking order’ of the window/panes. Firstly, add the following line to load in a second pane:
pane2%=FNwimp_loadwindow("<MyApp$Dir>.Templates","pane2",0)
With two panes you have to decide which one is going to be at the top of the stack in the final display, with the second pane behind that, followed by the ‘parent’ window behind the second pane. This can be extended to as many panes as you like. (By ‘behind’ and ‘top’ is meant only the stacking order: the panes and their parent window can be anywhere you choose on the screen i.e. they don’t have to abut or overlap, although often you will wish them to.)
We are going to make pane%
our topmost pane; pane2%
behind that and then the parent window main%
at the bottom of this stack of three windows (two panes and their common ‘parent’ window) - and, don’t forget, if we follow the steps correctly then DrWimp will automatically open the parent window in the right place.
So, change the section in PROCuser_openwindow
to become:
IF window%=main% THEN
xoff%=x%-FNwimp_getwindowvisiblesize(pane%,0)
PROCwimp_openwindowat(pane%,xoff%,y%,stack%)
yoff%=y%-FNwimp_getwindowvisiblesize(main%,1)
PROCwimp_openwindowat(pane2%,x%,yoff%,pane%)
ENDIF
This will open the first pane in the passed stack position and then open the second pane behind the first pane.
Now, in order to get DrWimp to open the parent window behind the second pane, we have to change FNuser_pane
to return the handle of the bottom-most pane (the last pane opened). Thus:
IF window%=main% THEN return%=pane2%
Change the relevant parts in PROCuser_closewindow
so when the main window is closed both the panes close:
IF window%=main% THEN
PROCwimp_closewindow(pane%)
PROCwimp_closewindow(pane2%)
ENDIF
and now check that it all works.
Some overall points
Finally, some overall points on panes:
It is best to avoid using panes having title bars. Only the parent window should control the on-screen movement. (But scroll-bars on panes work without difficulty.)
Note that, however many panes you attach to one parent window, only one of these panes (the bottom-most) must be assigned to the parent in FNuser_pane
. Do the ‘stacking’ as shown, within
PROCuser_openwindow
. Do not try to attach panes to panes!
If you have more than one window with panes, simply treat them as separate conditional coding items within
PROCuser_openwindow
,
PROCuser_closewindow
and
PROCuser_pane
.
Be careful to follow the described procedure accurately. If your initial window opening looks fine but things go awry when you use the ‘furniture’ on the parent window (e.g. scrolling, back icon, etc.) then you have probably forgotten something or got things out of order.
The normal operations of a pane work whether or not you set the ‘Pane’ option for a pane in its ‘window definition’. However, it is best to set this option if you are using writable icons in a pane. This will then ensure that the caret management and window focus are properly linked.
The Examples folder contains at least three applications using panes. Please examine these.
[Your !RunImage listing should now look like listing RI_04 in Tutor1
(apart from the REM
lines, perhaps). Do not destroy it as the following sections continue the tutorial from this stage.]
Top of page Back to Contents Previous Next